#ifndef __PLATFORM_LIB_LIST_H__
#define __PLATFORM_LIB_LIST_H__
#ifdef __cplusplus
extern "C"
{
#endif

#include "pf_common.h"

/******************************************************************************************************/

typedef struct pf_list pf_list_t;

typedef struct pf_list_node pf_list_node_t;

/*********************************************************************************************
Function Name:  pf_list_create
Description  :  Create a list
Inputs       :
Outputs      :  return value            :   The pointer of created list
ErrorCodes   :
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern pf_list_t* pf_list_create(void);

/*********************************************************************************************
Function Name:  pf_list_destory
Description  :  Destory a list
Inputs       :  pf_list_t* list         :   The list
Outputs      :  return value            :   Success or fail to destroy
ErrorCodes   :
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern int pf_list_destory(pf_list_t* list);

/*********************************************************************************************
Function Name:  pf_list_get_value
Description  :  Get value from a node
Inputs       :  pf_list_t_node* node    :   The one node of the list
Outputs      :  return value            :   The data of this node
ErrorCodes   :
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern void* pf_list_get_value(const pf_list_node_t* node);

/*********************************************************************************************
Function Name:  pf_list_head
Description  :  Get head node of the list
Inputs       :  pf_list_t* list         :   The list
Outputs      :  return value            :   The head node of the list
ErrorCodes   :
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern pf_list_node_t* pf_list_head(const pf_list_t* list);

/*********************************************************************************************
Function Name:  pf_list_tail
Description  :  Get tail node of the list
Inputs       :  pf_list_t* list         :   The list
Outputs      :  return value            :   The tail node of the list
ErrorCodes   :
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern pf_list_node_t* pf_list_tail(const pf_list_t* list);

/*********************************************************************************************
Function Name:  pf_list_next
Description  :  Get next node of the node
Inputs       :  pf_list_t_node* cur_node    :   One node of the list
Outputs      :  return value                :   The next node of the input node
ErrorCodes   :
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern pf_list_node_t* pf_list_next(const pf_list_node_t* cur_node);

/*********************************************************************************************
Function Name:  pf_list_prev
Description  :  Get prev node of the node
Inputs       :  pf_list_t_node* cur_node    :   One node of the list
Outputs      :  return value                :   The previous node of the input node
ErrorCodes   :
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern pf_list_node_t* pf_list_prev(const pf_list_node_t* cur_node);

/*********************************************************************************************
Function Name:  pf_list_push_front
Description  :  Add a new node to the head of a list
Inputs       :  pf_list_t* list             :   The list pointer
                void* value                 :   The data which push front
Outputs      :  return value                :   Success or fail to push
ErrorCodes   :  PF_ENOMEM                   :   Out of memory
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern int pf_list_push_front(pf_list_t* list, void* value);

/*********************************************************************************************
Function Name:  pf_list_push_back
Description  :  Add a new node to the tail of a list
Inputs       :  pf_list_t* list             :   The list pointer
                void* value                 :   The data which push back
Outputs      :  return value                :   Success or fail to push
ErrorCodes   :  PF_ENOMEM                   :   Out of memory
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern int pf_list_push_back(pf_list_t* list, void* value);

/*********************************************************************************************
Function Name:  pf_list_pop_front
Description  :  Erase a node from the head of a list and return it's value
Inputs       :  pf_list_t* list             :   The list pointer
Outputs      :  return value                :   The node's value which erases the head node
ErrorCodes   :
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern void* pf_list_pop_front(pf_list_t* list);

/*********************************************************************************************
Function Name:  pf_list_pop_back
Description  :  erase a node from the tail of a list and return it's value
Inputs       :  pf_list_t* list             :   The list pointer
Outputs      :  return value                :   The node's value which erases the tail node
ErrorCodes   :
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern void* pf_list_pop_back(pf_list_t* list);

/*********************************************************************************************
Function Name:  pf_list_insert
Description  :  Insert a node behind a specify node
Inputs       :  pf_list_t* list             :   The list pointer
                pf_list_t_node* node        :   One node of the list
                void* value                 :   The inserted data
Outputs      :  return value                :   Success or fail to insert
ErrorCodes   :  PF_ENOMEM                   :   Out of memory
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern int pf_list_insert(pf_list_t* list, pf_list_node_t* node, void* value);

/*********************************************************************************************
Function Name:  pf_list_erase
Description  :  Erase a specify node and return it's value
Inputs       :  pf_list_t* list             :   The list pointer
                pf_list_t_node* node        :   The node need to erase
Outputs      :  return value                :   The erased node's data
ErrorCodes   :
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern void* pf_list_erase(pf_list_t* list, pf_list_node_t* node);

/*********************************************************************************************
Function Name:  pf_list_count
Description  :  Get node count of a list
Inputs       :  pf_list_t* list             :   The list pointer
Outputs      :  return value                :   The count of all nodes
ErrorCodes   :
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern uint32_t pf_list_count(const pf_list_t* list);

/*********************************************************************************************
Function Name:  pf_list_clear
Description  :  Erase all nodes of a list
Inputs       :  pf_list_t* list             :   The list pointer
Outputs      :  return value                :   Success or fail to clear
ErrorCodes   :
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern int pf_list_clear(pf_list_t* list);

/*********************************************************************************************
Function Name:  pf_list_for_each
Description  :  Traverse a list and callback
Inputs       :  pf_list_t* list                     :   The list pointer
                int forward                         :   1 : from head to tail
                                                        0 : from tail to head
                void* arg                           :   callback function 's param
                int (*cb)(void* arg, void* value)   :   callback function
Outputs      :
ErrorCodes   :
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern int32_t pf_list_for_each(const pf_list_t* list,
                                int forward,
                                void* arg,
                                int (*cb)(void* arg, pf_list_node_t* node));

/*********************************************************************************************
Function Name:  pf_list_sort
Description  :  Sort the list
Inputs       :  pf_list_t* list                       :   The list pointer
                int (*comp)(const void*, const void*) :   The compare function
Outputs      :  return value                          :   Success or fail to sort
ErrorCodes   :
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern int pf_list_sort(pf_list_t* list,
                        int (*comp)(const void*, const void*));

/*********************************************************************************************
Function Name:  pf_list_qsort
Description  :  Quick sort the list
Inputs       :  pf_list_t* list                       :   The list pointer
                int (*comp)(const void*, const void*) :   The compare function
Outputs      :  return value                          :   Success or fail to sort
ErrorCodes   :
History      :
---------------------------------------------------------------------------------------------
Author                 Date                          Comments
zhanggp                2011-06-23                    create
**********************************************************************************************/
extern int pf_list_qsort(pf_list_t* list, 
                         int (*comp)(const void*, const void*));

#if 0
/* serialization (maybe later) */
extern int32_t pf_list_serialize(const pf_list_t* list,
                                 char* buffer,
                                 int32_t size);

extern pf_list_t* pf_list_deserialize(const char* data);*/
#endif

/******************************************************************************************************/

#ifdef __cplusplus
}
#endif
#endif /* #ifndef __PLATFORM_LIB_LIST_H__ */


